home *** CD-ROM | disk | FTP | other *** search
/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / basic / pbclone.exe / PBCLONE.DOC < prev    next >
Text File  |  1993-01-12  |  50KB  |  1,084 lines
  1.                      The PBClone Library
  2.                    =---------------------=
  3.                          Version 2.1
  4.  
  5.     PBCLONE  Copyright (c) 1990-1993  Thomas G. Hanlin III
  6.  
  7.  
  8.  
  9. Use of LIBMAT or LIBWIZ is strongly recommended for creating
  10. the initial PBClone library.  You should be able to get these
  11. utilities from the same place you got this library.
  12.  
  13. This is PBClone, a library of over 550 assembly language and
  14. BASIC routines for use with Microsoft's BASIC compilers:
  15. Bascom, PDS, QuickBasic and Visual BASIC for DOS.  The PBClone
  16. collection is copyrighted and may be distributed only under the
  17. following conditions:
  18.  
  19.    All PBClone files must be distributed together as a unit.
  20.    No files may be altered, added, or deleted from this unit.
  21.  
  22. You use this library at your own risk.  It has been tested by
  23. me on my own computer, but I will not assume any responsibility
  24. for any problems which PBClone may cause you.  If you do run
  25. into a problem, please let me know about it, and I will do my
  26. best to verify and repair it.
  27.  
  28. It is expected that if you find PBClone useful, you will
  29. register your copy.  You may not use PBClone routines in
  30. programs intended for sale unless you have registered.
  31.  
  32. Registration gets you the latest version of PBClone, complete
  33. with full source code.  The assembly language code is designed
  34. for MASM 6.0 and may require alteration for other assemblers.
  35.  
  36. You will need to have a complete set of PBClone .OBJ files for
  37. LibWiz to work.  Create a fresh subdirectory and extract the
  38. BASIC sources from PBC$BAS.ZIP (or .LZH, etc).  Compile them
  39. all.  The following DOS command will do it:
  40.  
  41.    FOR %x IN (*.BAS) DO BC %x /o;
  42.  
  43. Now extract the .OBJ files from PBC$MAIN.LIB into the same
  44. directory, using the UnLib utility that comes with LibWiz.
  45. Finally, extract the .OBJ files from PBC$NEAR.LIB as well. This
  46. gives you a complete set of .OBJs for PBClone, allowing LibWiz
  47. to create a custom PBClone library for you.
  48.  
  49. The VB-DOS compiler always uses far strings.  For it, you must
  50. use the .OBJs from PBC$FAR.LIB instead of PBC$NEAR.LIB.
  51.  
  52. With PDS, you have a choice between near and far strings.  To
  53. use far strings, use the /FS switch when compiling, and use the
  54. .OBJs from PBC$FAR.LIB instead of PBC$NEAR.LIB.
  55.  
  56.                      Creating .QLB files
  57.  
  58.  
  59.  
  60. If you like to use the BASIC editor/environment, you will need
  61. to create a .QLB version of the library to complement the .LIB
  62. version.  LIBWIZ can do it for you, or you can do it manually.
  63. This is done using the LINK.EXE utility that came with your
  64. compiler.  The exact parameters differ slightly depending on
  65. which version of the compiler you have.  For QuickBasic, it
  66. looks something like this:
  67.  
  68.    LINK libname.LIB/Q/SE:1024,libname.QLB,NUL,BQLB45;
  69.  
  70. The BQLB45 file is for QuickBasic 4.5.  This should be replaced
  71. by BQLB40 or BQLB41 for QuickBasic 4.0 (check your files to see
  72. which you have).  For BASCOM 6.0-7.1, also called Professional
  73. Development System or PDS, use QBXQLB instead of BQLB45.  For
  74. VB-DOS, use VBDOSQLB instead of BQLB45.
  75.  
  76. Since you'll probably want to do this again in the future when
  77. you get a new version of BasWiz or PBClone, I'd suggest you
  78. create a batch file or alias to do the work for you.  If you
  79. have 4DOS, an alias such as the following will do it:
  80.  
  81.    ALIAS QLB LINK %%1.LIB/Q/SE:1024,%%1.QLB,NUL,BQLB45;
  82.  
  83. In this case, you can do the conversion simply by typing:
  84.  
  85.    QLB libname
  86.  
  87.                      The TSR File Viewer
  88.  
  89.  
  90.  
  91. Since there are hundreds of routines in PBClone, it isn't
  92. always exactly easy to remember which routine you want or how
  93. to use it.  This is a particular problem when you're in the
  94. middle of writing a program.  So, I've written a TSR file
  95. viewer... it's crude, but it gets the job done.
  96.  
  97. Just type "FV" to install the TSR.  Alt-V activates it.  "FV
  98. /D" removes it from memory.
  99.  
  100.      !!! ----== NOTE ==---- !!!
  101. Please check FV with a nonessential application first!  It
  102. appears to work fine in the QuickBasic environment, but it
  103. locks up my favorite editor, so I can't guarantee that it will
  104. behave properly in all circumstances.
  105.  
  106. First, FV will ask you for the file to view.  This may contain
  107. drive and subdirectory information as well as the file name.
  108. Second, you will be asked for a search string.  If you enter a
  109. search string, viewing will start at the part of the file that
  110. contains that search string.  If you just press enter, viewing
  111. will start at the beginning of the file.  The file will be
  112. presented to you one page at a time.  I suggest viewing
  113. PBCLONE.DOC or PBCLONE.INF.
  114.  
  115. FV was written in BASIC using Crescent's P.D.Q. library, with
  116. the "simplified" TSR handler (which doesn't seem to have been
  117. entirely debugged).  Then again, TSRs are a tricky matter,
  118. especially with BASIC...
  119.  
  120.                         General Notes
  121.  
  122.  
  123.  
  124. The initial version of PBClone had only one manual.  However,
  125. since there are so many routines, I've split the manual into a
  126. general documentation file and a reference manual.  You won't
  127. want to print PBCLONE.MAN unless you have a lot of time and
  128. printer paper!  In contrast, this file (PBCLONE.DOC) has been
  129. kept small to allow ready printing.  It contains general notes,
  130. cross-reference listings of the routines, and assorted charts.
  131.  
  132. Many of the routines in PBClone are similar to routines of the
  133. same name in ADVBAS and/or ProBas.  The key here is "similar"--
  134. they don't necessarily work the same way and may not produce
  135. the same results.  If you intend to convert from ADVBAS or
  136. ProBas to PBClone, read the documentation carefully.
  137.  
  138. When a PBClone returns a Boolean (on or off) value, it will
  139. always be 0 if off, -1 if on; this is unlike ProBas, which
  140. would often return any non-zero value for an "on" state.
  141. Booleans passed to PBClone may still use any non-zero value to
  142. indicate a "true" or "on" condition, however.
  143.  
  144. Critical error handling has been incorporated into all disk and
  145. device routines.  You will never have to worry about "R>etry,
  146. A>bort, I>gnore" again, so long as you use PBClone for your
  147. disk and device management.
  148.  
  149. PBClone file handling is very flexible but may be confusing to
  150. people used to BASIC's strongly-moded files.  PBClone file
  151. handling is most similar to BASIC files opened in BINARY mode.
  152. You may read or write any amount of information at a time.
  153. After each read or write takes place, the file pointer is
  154. updated appropriately, so you can use sequential access
  155. techniques without further effort.  Random access is also
  156. possible, using FSetLoc/FSetOfs/FSetRec to set the file pointer
  157. position.  Those of you who are familiar with C or Pascal file
  158. handling will notice strong similarities in this approach,
  159. which is based on techniques that have long been standard in
  160. the industry.
  161.  
  162. Many routines are available both as SUBprograms and as
  163. FUNCTIONs.  The former is for compatibility with older programs
  164. which were designed before BASIC was capable of using
  165. FUNCTIONs.  You may use either, of course, although the
  166. FUNCTION version of a routine is often more convenient.
  167.  
  168.                         General Notes
  169.  
  170.  
  171.  
  172. The PBClone library can be used in conjunction with other
  173. libraries.  If there is a conflict in routine names between the
  174. two libraries, the OBJTOOL utility can be used to rename one or
  175. the other routine.  Due to the large size of PBClone, you will
  176. probably need to select just the routines you need, rather than
  177. combining the entire libraries, in order to avoid overflowing
  178. LINK limitations.  OBJTOOL can help you find out which routines
  179. are in what modules.  The LIB utility can be used to alter
  180. existing libraries, or you can build your own custom libraries
  181. from the ground up, using LibWiz.  See the LIB_BI.DOC and
  182. LIBRARY.TXT files if you are not familiar with libraries.
  183.  
  184. LibMatic, LibWiz and ObjTool are included on the sampler disk
  185. that comes with the registered version of PBClone.  They should
  186. also be available at your local BBS.
  187.  
  188. If you have not used ADVBAS, ProBas, or PBClone before, you may
  189. be unfamiliar with the array handling conventions used here.
  190. In alm